package independence.hibernate;

import java.io.Serializable;
import java.util.Collection;
import java.util.List;

/**
 * Interface defining all default operations of a data access
 * object implementation.
 * 
 * @param <T> The class type of the persistent object.
 * @param <ID>	The type of the persistent object's id field.
 * 
 * @author TK, TK Assembled
 */
public interface GenericDAO<T, ID extends Serializable> {
	/**
	 * Persists a new entry to the database with a default timeout of 100 seconds.
	 * @param value	<T> The value object to persist.
	 */
	public void persist(T value);
	/**
	 * Persists a new entry to the database with a timeout specified by <code>timeout</code>.
	 * @param value		<T> The value object to persist.
	 * @param timeout	<Integer> The time in seconds to wait before canceling this operation.
	 */
	public void persist(T value, Integer timeout);
	/**
	 * Persists a collection of <code>T</code> instances to the database with a default timeout
	 * of 100 seconds.
	 * @param collection	A collection of <code>T</code> objects to persist to the database.
	 */
	public void persistAll(Collection<T> collection);
	/**
	 * Persists a collection of <code>T</code> instances to the database with a default timeout
	 * of 100 seconds.
	 * @param collection	A collection of <code>T</code> objects to persist to the database.
	 * @param timeout		<Integer> The time in seconds to wait before canceling this operation.
	 */
	public void persistAll(Collection<T> collection, Integer timeout);
	/**
	 * Persists or updates a value in the database depending on its status:
	 * whether or not it exists in the database. Has a default timeout of 100 seconds.
	 * @param value	<T> The value to persist/update in the database.
	 */
	public void persistOrUpdate(T value);
	/**
	 * Persists or updates a value in the database with a timeout specified by <code>timeout</code>.
	 * @param value		<T> The value to persist/update in the database.
	 * @param timeout	<Integer> The time in seconds to wait before canceling this operation.
	 */
	public void persistOrUpdate(T value, Integer timeout);
	/**
	 * Persists or updates all instances of <code>T</code> in <code>collection</code> with a default timeout
	 * of 100 seconds.
	 * @param collection	A collection of <code>T</code> instances to persist/update in the database.
	 */
	public void persistOrUpdateAll(Collection<T> collection);
	/**
	 * Persists or updates all instances of <code>T</code> in <code>collection</code> with a timeout of 
	 * <code>timeout</code> seconds.
	 * @param collection	A collection of <code>T</code> instances to persist/update in the database.
	 * @param timeout		<Integer> The time in seconds to wait before canceling this operation.
	 */
	public void persistOrUpdateAll(Collection<T> collection, Integer timeout);
	/**
	 * Updates an existing entry in the database with a default timeout of 100 seconds.
	 * @param value	<T> The existing value object to update in the database.
	 */
	public void update(T value);
	/**
	 * Updates an existing entry in the database with a timeout specified by <code>timeout</code>.
	 * @param value		<T> The value to persist/update in the database.
	 * @param timeout	<Integer> The time in seconds to wait before canceling this operation.
	 */
	public void update(T value, Integer timeout);
	/**
	 * Updates all existing persistent entities of <code>T</code> found in <code>collection</code> in the database
	 * with a default timeout of 100 seconds.
	 * @param collection	A collection of <code>T</code> entities to update in the database.
	 */
	public void updateAll(Collection<T> collection);
	/**
	 * Updates all existing persistent entities of <code>T</code> found in <code>collection</code> in the database
	 * with a timeout of <code>timeout</code> seconds.
	 * @param collection	A collection of <code>T</code> entities to update in the database.
	 * @param timeout		<Integer> The time in seconds to wait before canceling this operation.
	 */
	public void updateAll(Collection<T> collection, Integer timeout);
	/**
	 * Deletes a matching object from the database with a default timeout of 100 seconds.
	 * @param value	<T> The object to delete from the database.
	 */
	public void delete(T value);
	/**
	 * Deletes a matching object from the database with a timeout of <code>timeout</code> seconds.
	 * @param value		<T> The value to delete from the database.
	 * @param timeout	<Integer> The time in seconds to wait before canceling this operation.
	 */
	public void delete(T value, Integer timeout);
	/**
	 * Deletes all persistent entities of <code>T</code> in <code>collection</code> from the database
	 * with a default timeout of 100 seconds.
	 * @param collection	A collection of persistent entities of <code>T</code> to delete from the database.
	 */
	public void deleteAll(Collection<T> collection);
	/**
	 * Deletes all persistent entities of <code>T</code> in <code>collection</code> from the database with a timeout
	 * of <code>timeout</code> seconds.
	 * @param collection	A collection of persistent entities of <code>T</code> to delete from the database.
	 * @param timeout		<Integer> The time in seconds to wait before cancelling this operation.
	 */
	public void deleteAll(Collection<T> collection, Integer timeout);
	/**
	 * Returns an object by its <code>Serializable</code> id field with a default timeout of 100 seconds.
	 * @param value	<ID> The unique identifier number of the requested object.
	 * @return	<T> The requested object or null if none can be found.
	 */
	public T getById(ID value);
	/**
	 * Returns an object by its <code>Serializable</code> id field with a timeout specified by
	 * <code>timeout</code>.
	 * @param value		<ID> The <code>Serializable</code> id field identifying a unique record in the database.
	 * @param timeout	<Integer> The time in seconds to wait before canceling this operation.
	 * @return <T> The requested object or null if none can be found.
	 */
	public T getById(ID value, Integer timeout);
	/**
	 * Returns an object with a property of <code>name</code> matching <code>value</code> with a default
	 * timeout of 100 seconds.
	 * @param name	<String> The name of the attribute to match.
	 * @param value	<Object> The requested value to match in the object.
	 * @return	The requested object or null if no match can be found.
	 */
	public T getByAttribute(String name, Object value);
	/**
	 * Returns an object with a property of <code>name</code> matching <code>value</code> with a timeout of <code>
	 * timeout</code> seconds..
	 * @param name	<String> The name of the attribute to match.
	 * @param value	<Object> The requested value to match in the object.
	 * @param timeout <Integer> The time in seconds to wait before canceling this operation.
	 * @return	The requested object or null if no match can be found.
	 */
	public T getByAttribute(String name, Object value, Integer timeout);
	/**
	 * Returns a List of all persisted instances of <code>T</code> with no limit and a timeout of 100 seconds.
	 * @return	All persisted instances of <code>T</code>.
	 */
	public List<T> getAll();
	/**
	 * Returns a List of all persisted instances of <code>T</code> with no limit and a timeout of <code>timeout</code> seconds.
	 * @param timeout	<Integer> The time in seconds to wait before cancelling this operation.
	 * @return	All persisted instances of <code>T</code>.
	 */
	public List<T> getAll(Integer timeout);
	/**
	 * Returns a "paginated" List of the persisted entries of <code>T</code>. This operation has a timeout
	 * specified by <code>timeout</code> and returns <code>limit</code> amount of entries beginning at <code>
	 * start</code>.
	 * @param timeout	<Integer> The time in seconds to wait before canceling this operation.
	 * @param start		<Integer> The id of the "starting point entry" from which to search the database.
	 * @param limit		<Integer> The limit of entries to return.
	 * @return	A List of <code>limit</code> entities of <code>T</code> from <code>start</code> onward.
	 */
	public List<T> getAll(Integer timeout, Integer start, Integer limit);
	/**
	 * Returns a List of all persisted instances of <code>T</code> with
	 * a property of <code>name</code> matching <code>value</code> with a default timeout of
	 * 100 seconds.
	 * @param name	<String> The name of the property to match in the persistent class.
	 * @param value	The value of the <code>name</code> property to match.
	 * @return	A List of all matching instances of <code>T</code>.
	 */
	public List<T> getAllByAttribute(String name, Object value);
	/**
	 * Returns a List of all persisted instances of <code>T</code> with a property of <code>name</code> 
	 * matching <code>value</code> with a timeout of <code>timeout</code> seconds.
	 * @param name		<String> The name of the property to match in the persistent entity.
	 * @param value		The value of the <code>name</code> property to find a match for.
	 * @param timeout	<Integer> The time in seconds to wait before canceling this operation.
	 * @return	A List of all matching instances of <code>T</code>.
	 */
	public List<T> getAllByAttribute(String name, Object value, Integer timeout);
	/**
	 * Returns a List of <code>limit</code> persisted instances of <code>T</code> with a property of <code>name</code>
	 * matching <code>value</code> from <code>start</code> on, with a timeout of <code>timeout</code> seconds.
	 * @param name		<String> The name of the property to match in the persistent entity.
	 * @param value		The value of the <code>name</code> property to find a match for. 
	 * @param timeout	<Integer> The time in seconds to wait before canceling this operation.
	 * @param start		<Integer> The id of the "starting point entry" from which to search the database.
	 * @param limit		<Integer> The limit of entries to return.
	 * @return	A List of all <code>T</code> instances having a property of <code>name</code> matching a value of <code>value</code>
	 * 			from <code>start</code> onward with a limit of <code>limit</code> entries and a timeout of <code>
	 * 			timeout</code> seconds.
	 */
	public List<T> getAllByAttribute(String name, Object value, Integer timeout, Integer start, Integer limit);
}
